home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
EnigmA Amiga Run 1998 July
/
EnigmA AMIGA RUN 29 (1998)(G.R. Edizioni)(IT)[!][issue 1998-07 & 08].iso
/
earkit
/
socket
/
miami3
/
miamisdk
/
doc
/
miamipcap.doc
< prev
next >
Wrap
Text File
|
1998-05-24
|
20KB
|
795 lines
TABLE OF CONTENTS
miamipcap.library/--general information--
miamipcap.library/--PCap callbacks--
miamipcap.library/MiamiPCapAmigaBPFHandle
miamipcap.library/MiamiPCapAmigaDump
miamipcap.library/MiamiPCapAmigaDumpClose
miamipcap.library/MiamiPCapAmigaDumpOpen
miamipcap.library/MiamiPCapAmigaFile
miamipcap.library/MiamiPCapBPFImage
miamipcap.library/MiamiPCapClose
miamipcap.library/MiamiPCapCompile
miamipcap.library/MiamiPCapDatalink
miamipcap.library/MiamiPCapDispatch
miamipcap.library/MiamiPCapGeterr
miamipcap.library/MiamiPCapInit
miamipcap.library/MiamiPCapIsSwapped
miamipcap.library/MiamiPCapLookupdev
miamipcap.library/MiamiPCapLookupnet
miamipcap.library/MiamiPCapLoop
miamipcap.library/MiamiPCapMajorVersion
miamipcap.library/MiamiPCapMinorVersion
miamipcap.library/MiamiPCapNext
miamipcap.library/MiamiPCapOpenLive
miamipcap.library/MiamiPCapOpenOffline
miamipcap.library/MiamiPCapPerror
miamipcap.library/MiamiPCapSetCallbackType
miamipcap.library/MiamiPCapSetFilter
miamipcap.library/MiamiPCapSnapshot
miamipcap.library/MiamiPCapStats
miamipcap.library/MiamiPCapStrerror
miamipcap.library/--general information--
Miami:libs/miamipcap.library is an implementation of the
libpcap software suite, a packet monitoring mechanism built on top of
BPF, which provides high-level filtering functions.
MiamiPCap is implemented on top of MiamiBPF, which in turn uses the
packet monitoring mechanism in Miami 1.9.3 and above, i.e. MiamiPCap
only works with the registered version of Miami.
The main advantage of MiamiPCap over lower-level packet monitoring
mechanisms is that MiamiPCap allows an application to specify ASCII
filter strings to select a set of packets, e.g. something like
icmp[0] != 8 and icmp!= 0
which would select all ICMP packets that are not echo requests or
replies.
MiamiPCap has a built-in compiler and code optimizer to convert such
ASCII strings into the binary BPF program code sequences required by
the underlying MiamiBPF suite.
The primary use of MiamiPCap is in programs such as TCPDump.
miamipcap.library/--PCap callbacks-- miamipcap.library/--PCap callbacks--
PCap calls a callback function in your program for each packet
received, which has not been filtered out. The proper declaration of
the callback function is:
void pcapcallback(void *user,struct pcap_pkthdr *pkthdr,char
*packet);
The default CPU type for callbacks is MIAMICPU_M68KREG (parameters
passed on the stack), regardless of which API is used.
miamipcap.library versions 3 and higher support the new call
MiamiPCapSetCallbackType() to change the CPU type used for callbacks.
miamipcap.library/MiamiPCapAmigaBPFHandle
NAME
MiamiPCapAmigaBPFHandle -- returns the BPF handle associated with a
pcap unit
SYNOPSIS
bpfhandle = MiamiPCapAmigaBPFHandle( p );
D0 A0
int MiamiPCapAmigaBPFHandle( pcap_t *p );
FUNCTION
Returns the BPF handle associated with a pcap unit.
INPUTS
p - pcap unit handle
RESULT
bpfhandle (D0) - BPF handle
miamipcap.library/MiamiPCapAmigaDump miamipcap.library/MiamiPCapAmigaDump
NAME
MiamiPCapAmigaDump -- dump a packet to a save file
SYNOPSIS
MiamiPCapAmigaDump( filehandle, h, sp );
A0 A1 A2
void MiamiPCapAmigaDump( pcap_dumper_t *filehandle, struct
pcap_pkthdr *h, u_char *sp );
FUNCTION
Dumps the packet specified in sp to the specified save file, using
the packet header passed in h.
The file handle MUST have been created by an earlier call to
MiamiPCapAmigaDumpOpen.
INPUTS
filehandle - file handle
h - packet header
sp - data
miamipcap.library/MiamiPCapAmigaDumpClose
NAME
MiamiPCapAmigaDumpClose -- closes an open save file
SYNOPSIS
MiamiPCapAmigaDumpClose( filehandle );
A0
void MiamiPCapAmigaDumpClose( pcap_dumper_t *filehandle );
FUNCTION
Closes the indicated save file.
The file must have been opened earlier by a call to
MiamiPCapAmigaDumpOpen.
INPUTS
filehandle - file handle
miamipcap.library/MiamiPCapAmigaDumpOpen
NAME
MiamiPCapAmigaDumpOpen -- opens a save file to dump packets
SYNOPSIS
filehandle = MiamiPCapAmigaDumpOpen( p, fname );
D0 A0 A1
pcap_dumper_t *MiamiPCapAmigaDumpOpen( pcap_t *p, char *fname );
FUNCTION
Opens a save file for the specified unit. The returned file handle
can later be used in MiamiPCapAmigaDump calls to dump packets to the
save file.
A return value of NULL indicates that an error has occured.
The filehandle later needs to be closed by calling
MiamiPCapAmigaDumpClose.
INPUTS
p - pcap unit handle
fname - file name
RESULT
filehandle (D0) - file handle
miamipcap.library/MiamiPCapAmigaFile miamipcap.library/MiamiPCapAmigaFile
NAME
MiamiPCapAmigaFile -- return Amiga file handle for save file
SYNOPSIS
handle = MiamiPCapAmigaFile( p );
D0 A0
BPTR MiamiPCapAmigaFile( pcap_t *p );
FUNCTION
returns the Amiga file handle for the current save file. For pOS a
(struct pOS_FileHandle *) is returned instead of a BPTR.
INPUTS
p - pcap unit handle
RESULT
handle (D0) - filehandle
miamipcap.library/MiamiPCapBPFImage miamipcap.library/MiamiPCapBPFImage
NAME
MiamiPCapBPFImage -- disassemble a compiled BPF instruction
SYNOPSIS
d = MiamiPCapBPFImage( pi, n );
D0 A0 D0
char *MiamiPCapBPFImage( struct bpf_insn *pi, int n );
FUNCTION
Disassembles a compiled BPF instruction into a text string.
The two parameters are the BPF instruction and the offset (PC) of the
instruction relative to the BPF program.
The returned string contains the disassembled text representing the
BPF instruction. The text pointer points to static space that does
not have to be freed. It is overwritten with the next call to
MiamiPCapBPFImage.
INPUTS
pi - bpf instruction
n - instruction offset (PC)
RESULT
d (D0) - disassembled code
miamipcap.library/MiamiPCapClose miamipcap.library/MiamiPCapClose
NAME
MiamiPCapClose -- closes a pcap unit
SYNOPSIS
MiamiPCapClose( p );
A0
void MiamiPCapClose( pcap_t *p );
FUNCTION
Closes a pcap unit which was previously opened by a call to
MiamiPCapOpenLive or MiamiPCapOpenOffline.
INPUTS
p - pcap unit handle
miamipcap.library/MiamiPCapCompile miamipcap.library/MiamiPCapCompile
NAME
MiamiPCapCompile -- compile a filter string into a BPF program
SYNOPSIS
error = MiamiPCapCompile( p, program, buf, optimize, mask );
D0 A0 A1 A2 D0 D1
int MiamiPCapCompile( pcap_t *p, struct bpf_program *program, char
*buf, int optimize, bpf_u_int32 mask );
FUNCTION
Compiles the filter string passed in 'buf' into a BPF program. The
resulting program is stored in the structure passed in 'program'.
If 'optimize' is different from zero then the BPF code optimizer is
executed on the resulting program to compress the code. 'optimize'
should always be used except if you suspect a bug in the optimizer.
'mask' is the netmask for the interface the program is supposed to
execute on.
The function returns zero on success and a non-zero value on failure.
INPUTS
p - pcap unit handle
program - BPF program structure
buf - filter string
optimize - optimize flag
mask - netmask
RESULT
error (D0) - error code
miamipcap.library/MiamiPCapDatalink miamipcap.library/MiamiPCapDatalink
NAME
MiamiPCapDatalink -- return the datalink layer packet type
SYNOPSIS
type = MiamiPCapDatalink( p );
D0 A0
int MiamiPCapDatalink( pcap_t *p );
FUNCTION
returns the datalink layer packet type, i.e. one of the DLT_...
constants in <net/bpf.h>. For MiamiBPF the only possible value is
currently DLT_MIAMI.
INPUTS
p - pcap unit handle
RESULT
type (D0) - type
miamipcap.library/MiamiPCapDispatch miamipcap.library/MiamiPCapDispatch
NAME
MiamiPCapDispatch -- collect and process packets
SYNOPSIS
count = MiamiPCapDispatch( p, cnt, callback, user );
D0 A0 D0 A1 A2
int MiamiPCapDispatch( pcap_t *p, int cnt, pcap_handler callback,
u_char *user );
FUNCTION
Collect and process packets for the specified pcap unit.
cnt specifies the maximum number of packets to process before
returning. A cnt of -1 processes all the packets received in one
buffer. A cnt of 0 processes all packets until an error occurs (or
EOF is reached for a save file).
callback specifies a PCap callback functions, as explained in -- PCap
callbacks --. The parameter 'user' is the user parameter for the
callback function.
The returned value contains the number of packets read. 0 is
returned if EOF is reached in a save file. -1 is returned to
indicate an error.
INPUTS
p - pcap unit handle
cnt - maximum number of packets
callback - packet callback
user - user data for callback
RESULT
count (D0) - packet count
miamipcap.library/MiamiPCapGeterr miamipcap.library/MiamiPCapGeterr
NAME
MiamiPCapGeterr -- returns the current error string buffer
SYNOPSIS
errbuf = MiamiPCapGeterr( p );
D0 A0
char *MiamiPCapGeterr( pcap_t *p );
FUNCTION
Returns a pointer to the current error string buffer, i.e. the ebuf
parameter for the MiamiPCapOpenLive or MiamiPCapOpenOffline call
INPUTS
p - pcap unit handle
RESULT
errbuf (D0) - error buffer
miamipcap.library/MiamiPCapInit miamipcap.library/MiamiPCapInit
NAME
MiamiPCapInit -- initialize MiamiPCap
SYNOPSIS
MiamiPCapInit( MiamiBase, SocketBase );
A0 A0
void MiamiPCapInit( struct Library *MiamiBase, struct Library
*SocketBase );
FUNCTION
Initializes MiamiPCap for use. You MUST call this function before
calling any other function in miamipcap.library.
INPUTS
MiamiBase - Library base of miami.library
SocketBase - Library base of bsdsocket.library
NOTE
You need to open miami.library V6 or higher and bsdsocket.library V4
or higher before calling this function. Mind the version numbers !
Using miamipcap.library with older library versions will cause
crashes.
miamipcap.library/MiamiPCapIsSwapped miamipcap.library/MiamiPCapIsSwapped
NAME
MiamiPCapIsSwapped -- check byte order of save file
SYNOPSIS
bool = MiamiPCapIsSwapped( p );
D0 A0
int MiamiPCapIsSwapped( pcap_t *p );
FUNCTION
returns TRUE if the save file for this pcap unit uses a different
byte order than the current system, and FALSE if the byte order is
the same.
INPUTS
p - pcap unit handle
RESULT
bool (D0) - bool
miamipcap.library/MiamiPCapLookupdev miamipcap.library/MiamiPCapLookupdev
NAME
MiamiPCapLookupdev -- finds a suitable interface name
SYNOPSIS
name = MiamiPCapLookupdev( ebuf );
D0 A0
char *MiamiPCapLookupdev( char *ebuf );
FUNCTION
Finds a suitable interface name for use with MiamiPCap, that can be
used as a default name if the user has not explicitly specified an
interface.
A NULL return value indicates that an error has occured. If the
return value is non-NULL, then it is a pointer to a valid interface
name in static storage, i.e. the pointer does not have to be freed,
but the name will be overwritten by future calls to
MiamiPCapLookupdev.
INPUTS
ebuf - buffer for error string
RESULT
name (D0) - interface name
miamipcap.library/MiamiPCapLookupnet miamipcap.library/MiamiPCapLookupnet
NAME
MiamiPCapLookupnet -- finds the interface address and netmask
SYNOPSIS
error = MiamiPCapLookupnet( device, netp, maskp, ebuf );
D0 A0 A1 A2 A3
int MiamiPCapLookupnet( char *device, bpf_u_int32 *netp, bpf_u_int32
*maskp, char *ebuf );
FUNCTION
Finds the interface (IP) address and the netmask for the specified
interface.
The return code is zero for success and non-zero for failure, in
which case the error buffer will contain an error message.
The pointers netp and maskp need to point to variables of type
bpf_u_int32, which will be filled with the IP address and netmask of
the specified interface, respectively.
INPUTS
device - interface name
netp - pointer to address
maskp - pointer to netmask
ebuf - buffer for error string
RESULT
error (D0) - error code
miamipcap.library/MiamiPCapLoop miamipcap.library/MiamiPCapLoop
NAME
MiamiPCapLoop -- loop to collect and process packets
SYNOPSIS
count = MiamiPCapLoop( p, cnt, callback, user );
D0 A0 D0 A1 A2
int MiamiPCapLoop( pcap_t *p, int cnt, pcap_handler callback, u_char
*user );
FUNCTION
Same as MiamiPCapDispatch, but with one difference:
MiamiPCapDispatch returns as soon as some packets have been read (or
another condition such as a timeout or an error has occured).
MiamiPCapLoop keeps reading until cnt packets have been read or an
error has occured.
INPUTS
p - pcap unit handle
cnt - number of packets
callback - packet callback
user - user data for callback
RESULT
count (D0) - packet count
miamipcap.library/MiamiPCapMajorVersion
NAME
MiamiPCapMajorVersion -- return major version number for save file
SYNOPSIS
version = MiamiPCapMajorVersion( p );
D0 A0
int MiamiPCapMajorVersion( pcap_t *p );
FUNCTION
returns the major version number of the pcap used to write the save
file.
INPUTS
p - pcap unit handle
RESULT
version (D0) - version
miamipcap.library/MiamiPCapMinorVersion
NAME
MiamiPCapMinorVersion -- return minor version number for save file
SYNOPSIS
version = MiamiPCapMinorVersion( p );
D0 A0
int MiamiPCapMinorVersion( pcap_t *p );
FUNCTION
returns the minor version number of the pcap used to write the save
file.
INPUTS
p - pcap unit handle
RESULT
version (D0) - version
miamipcap.library/MiamiPCapNext miamipcap.library/MiamiPCapNext
NAME
MiamiPCapNext -- read one packet
SYNOPSIS
packet = MiamiPCapNext( p, h );
D0 A0 A1
u_char *MiamiPCapNext( pcap_t *p, struct pcap_pkthdr *h );
FUNCTION
Similar to MiamiPCapDispatch, but reads only a single packet and
returns the pointer to the packet data. No callback function is
called. The specified packet header is used as a template when
reading the packet.
INPUTS
p - pcap unit handle
h - packet header
RESULT
packet (D0) - packet data
miamipcap.library/MiamiPCapOpenLive miamipcap.library/MiamiPCapOpenLive
NAME
MiamiPCapOpenLive -- open a live pcap unit
SYNOPSIS
p = MiamiPCapOpenLive( device, snaplen, promisc, toms, ebuf );
D0 A0 D0 D1 D2 A1
pcap_t *MiamiPCapOpenLive( char *device, int snaplen, int promisc,
int toms, char *ebuf );
FUNCTION
Opens a live PCap monitoring unit, for the specified interface.
A return value of NULL indicates that an error has occured, in which
case the buffer bassed in ebuf will contain an ASCII error message.
snaplen is the maximum packet size you want PCap to preserve.
promisc is a boolean variable indicating promiscuous mode and
currently MUST be zero. Promiscuous mode is not currently supported
because of limitations in the Amiga SANA-II standard.
If toms is a non-zero value then it is considered a read timeout in
milliseconds for later calls to the packet monitoring functions. A
value of zero means 'no timeout', i.e. wait indefinitely.
The error string buffer passed to MiamiPCapOpenLive is used not only
for this single function call, but for ALL error strings resulting
from future function calls for this pcap unit.
INPUTS
device - interface name
snaplen - maximum packet length to copy
promisc - promisc mode, currently MUST be zero
toms - timeout in milliseconds
ebuf - buffer for error string
RESULT
p (D0) - pcap unit handle
miamipcap.library/MiamiPCapOpenOffline miamipcap.library/MiamiPCapOpenOffline
NAME
MiamiPCapOpenOffline -- open a savefile for reading
SYNOPSIS
p = MiamiPCapOpenOffline( fname, ebuf );
D0 A0 A1
pcap_t *MiamiPCapOpenOffline( char *fname, char *ebuf );
FUNCTION
Opens an offline PCap monitoring unit. Packets are read from the
specified file, not from the network. The file must have been
created by MiamiPCap earlier.
A return value of NULL indicates that an error has occured, in which
case the buffer bassed in ebuf will contain an ASCII error message.
The error string buffer passed to MiamiPCapOpenLive is used not only
for this single function call, but for ALL error strings resulting
from future function calls for this pcap unit.
INPUTS
fname - file name
ebuf - buffer for error string
RESULT
p (D0) - pcap unit handle
miamipcap.library/MiamiPCapPerror miamipcap.library/MiamiPCapPerror
NAME
MiamiPCapPerror -- prints the current pcap error string to the
console
SYNOPSIS
MiamiPCapPerror( p, prefix );
A0 A1
void MiamiPCapPerror( pcap_t *p, char *prefix );
FUNCTION
Prints the current pcap error string to the console, in the same
format used by the Un*x perror() function call.
INPUTS
p - pcap unit handle
prefix - error prefix
miamipcap.library/MiamiPCapSetCallbackType
NAME
MiamiPCapSetCallbackType -- set the CPU for callbacks (V3)
SYNOPSIS
success = MiamiPCapSetCallbackType( pi, c );
D0 A0 D0
long MiamiPCapSetCallbackType( pcap_t *pi, long c );
FUNCTION
Set the CPU used for callbacks, i.e. one of MIAMICPU_... The
default CPU is MIAMICPU_M68KREG, regardless of which API (68k or PPC)
is used. Other CPU types require special support in
miamipcap.library and Miami. If the requested CPU is not supported
for callbacks then FALSE is returned. Otherwise TRUE is returned and
all subsequent callbacks use the new CPU calling conventions.
INPUTS
pi - pcap unit handle
c - CPU type
RESULT
success (D0) - success indicator
miamipcap.library/MiamiPCapSetFilter miamipcap.library/MiamiPCapSetFilter
NAME
MiamiPCapSetFilter -- attach a program to a pcap unit as a filter
SYNOPSIS
error = MiamiPCapSetFilter( p, prog );
D0 A0 A1
int MiamiPCapSetFilter( pcap_t *p, struct bpf_program *prog );
FUNCTION
Ataches a compiled program to the specified pcap unit as a filter.
The program has to be a valid BPF program, typically returned by a
previous call to MiamiPCapCompile. The new filter replaces the
previous filter (if any).
A return code of zero indicates success, a non-zero return code
indicates failure.
INPUTS
p - pcap unit handle
prog - compiled program
RESULT
error (D0) - error code
miamipcap.library/MiamiPCapSnapshot miamipcap.library/MiamiPCapSnapshot
NAME
MiamiPCapSnapshot -- return the maximum snapshot length
SYNOPSIS
len = MiamiPCapSnapshot( p );
D0 A0
int MiamiPCapSnapshot( pcap_t *p );
FUNCTION
returns the maximum packet length used for snapshot (i.e. the value
passed in the snaplen parameter to MiamiPCapOpenLive.
INPUTS
p - pcap unit handle
RESULT
len (D0) - length
miamipcap.library/MiamiPCapStats miamipcap.library/MiamiPCapStats
NAME
MiamiPCapStats -- return packet statistics
SYNOPSIS
error = MiamiPCapStats( p, st );
D0 A0 A1
int MiamiPCapStats( pcap_t *p, pcap_stat *st );
FUNCTION
Returns statistics for the specified pcap unit handle, by
filling
in the statistics structure passed to the function.
If the returned error code is 0 then the contents of the statistics
structure are valid.
INPUTS
p - pcap unit handle
st - statistics
RESULT
error (D0) - error code
miamipcap.library/MiamiPCapStrerror miamipcap.library/MiamiPCapStrerror
NAME
MiamiPCapStrerror -- converts an error number to an error string
SYNOPSIS
errstr = MiamiPCapStrerror( errnum );
D0 D0
char *MiamiPCapStrerror( int errnum );
FUNCTION
Converts an error number into an error string. The returned pointer
points to static storage and does not have to be freed. It is
overwritten with the next call to MiamiPCapStrerror.
The returned pointer is independent of pcap units and NOT identical
to the error string buffer for any particular pcap unit.
INPUTS
errnum - error number
RESULT
errstr (D0) - error string